home *** CD-ROM | disk | FTP | other *** search
/ Almathera Ten Pack 2: CDPD 1 / Almathera Ten on Ten - Disc 2: CDPD 1.iso / pd / 301-325 / 325 / rexxhostlib / rexxhost.doc < prev    next >
Text File  |  1995-03-14  |  10KB  |  282 lines
  1. ========================== RexxHost.Library ==========================
  2. ======================================================================
  3. An Amiga shared library for creating/managing ARexx host environments.
  4. ======================================================================
  5.  
  6.                            -= Background =-
  7.  
  8. A  friend  of mine was busy developing a stock management program when
  9. he suddenly realized that an ARexx interface would be the only feature
  10. that wasn't already part of his project.  So he started to analyze, to
  11. program,  to  try - just to find out that it would be too much work to
  12. add it.
  13.     Some  months later a programmer who works for the same company
  14. I  am  working  for decided to rewrite his home-brewn assembler/linker
  15. program  to  interface to CygnusEd Professional.  The problem is:  his
  16. program  is written in assembly language, the standard host management
  17. routines are written in 'C'...
  18.     To  simplify  the host creation/management procedure I decided
  19. to  put the required routines as well as some extra code into a shared
  20. library,  easy  to  use  by  ANY  language (can you imagine AmigaBASIC
  21. controlling AmigaTeX?).
  22.  
  23.  
  24.                        -= Supplied material =-
  25.  
  26.         The RexxHostLib package contains the following files:
  27.         -----------------------------------------------------
  28.     FancyDemo..............    Demonstration program
  29.     FancyDemo.c............    Source code for demonstration program
  30.  
  31.     Interface.asm..........    Library support code
  32.     LibStartup.asm.........    Library support code
  33.  
  34.     Link.asm...............    Library glue routines
  35.  
  36.     LibMain.c..............    Library support code
  37.     RexxHostLib.c..........    Library support code
  38.     RexxHostBase.h.........    Library header file
  39.  
  40.     rexxhost.lib...........    Aztec 'C' linker library
  41.     rexxhost.library.......    Amiga shared library
  42.  
  43.     MakeFile...............    Library building-instructions
  44.  
  45.     Library.fd.............    Library function definitions
  46.  
  47.     testdemo.rexx..........    ARexx demonstration script
  48.  
  49.     RexxHost.doc...........    This file
  50.  
  51.  
  52.                            -= How to use =-
  53.  
  54. The  rexxhost.library needs ARexx (any version will do, v1.10 is best)
  55. to  work properly.  It needs to be opened EXPLICITELY, i.e.  it is not
  56. forced  into  memory by the ARexx server and CANNOT be loaded with the
  57. addlib() call in rexx-scriptfiles.  An unlimited number of callers may
  58. open   the   library,   it   is   100%   reentrant.    Just  like  the
  59. rexxsyslib.library   the   rexxhost.library   stays  in  memory  until
  60. explicitely expunged (e.g.  via "flushlibs" call from Workbench).
  61.     The  OpenLibrary()  call  returns  a pointer to a RexxHostBase
  62. structure (as defined in the RexxHostBase.h include file).  It has the
  63. following format:
  64.  
  65.         struct RexxHostBase
  66.         {
  67.             struct Library     rhb_Lib;
  68.             ULONG         rhb_SegList;
  69.  
  70.             struct RxsLib    *RexxSysBase;
  71.         };
  72.  
  73. The  pointer  to the RxsLib structure represents a pointer to the base
  74. of  the  rexxsyslib.library.  It can be copied by the calling process,
  75. the rexxsyslib.library does not need to be opened explicitely.
  76.     All library functions are "bullet proof", i.e. if the supplied
  77. arguments are illegal the function returns immediately. Note that this
  78. library  only contains basic support functions, you will still have to
  79. do command analysis, parsing and command processing on your own (which
  80. isn't difficult, look at the MinRexx sourcecode for an example).
  81.  
  82.  
  83.                            -= Compiling =-
  84.  
  85. A  Makefile  for Aztec 'C' is supplied.  Note that line 67 in the rexx
  86. include file 'rxslib.h' has to be corrected from:
  87.  
  88.     WORD rl_NumMsg;    /* pending count */
  89.  
  90. to:
  91.  
  92.     WORD rl_PgmMsg;    /* pending count */
  93.  
  94. or you will get a 'multiple entry' message from the compiler.
  95.  
  96.  
  97.                    -= RexxHost.Library Functions =-
  98.  
  99. CreateRexxHost - Create host MsgPort with supplied name
  100.  
  101. Usage:
  102. MsgPort = CreateRexxHost(HostName)
  103.   D0                       D0
  104.  
  105. This  function  tries  to  allocate a public messageport with a unique
  106. name.   If  a  port  with the supplied name does already exist NULL is
  107. returned.
  108.  
  109.  
  110. DeleteRexxHost - Remove host MsgPort
  111.  
  112. Usage:
  113. DeleteRexxHost(MsgPort)
  114.                  D0
  115.  
  116. A supplied MsgPort is removed from the system, freeing allocated signals
  117. and nodes.
  118.  
  119.  
  120. SendRexxCommand() - Send a command to the rexx server
  121.  
  122. Usage:
  123. Success = SendRexxCommand(HostPort,CommandString,FileExtension,HostName)
  124.   D0                         D0          D1             A0        A1
  125.  
  126. This  function  causes  the  rexx  server  to  execute  a script file.
  127. HostPort  must  point  to  the host MsgPort, CommandString points to a
  128. string   containing   the   name   of  the  command  to  be  executed.
  129. FileExtension   and   HostName   are   optional   and   may  be  NULL.
  130. FileExtension  defines  the  script  file name extension for this host
  131. (for  standard rexx scripts this is ".rexx", for CygnusEd Professional
  132. it  is  ".ced").   HostName  is  supplied to allow the host to address
  133. different  sub-hosts, such as different windows a text editor may have
  134. open.   This  function returns FALSE (0) if the command cannot be sent
  135. (rexx may not be running) and TRUE (1) if the message has been posted.
  136.  
  137.  
  138. FreeRexxCommand() - Free the contents of a RexxMsg
  139.  
  140. Usage:
  141. FreeRexxCommand(RexxMessage)
  142.                     D0
  143.  
  144. Having  successfully  called  SendRexxCommand()  the  rexx server will
  145. return the RexxMsg with result flags set.  This kind of message cannot
  146. be  replied (since it already has been replied by the rexx server) but
  147. has  to  be  deallocated.   Be  sure  to examine the result code flags
  148. before you remove the RexxMsg.
  149.  
  150.  
  151. ReplyRexxCommand() - Returns a RexxMsg to the rexx server
  152.  
  153. Usage:
  154. ReplyRexxCommand(RexxMessage,Primary,Secondary,Result)
  155.                      D0         D1      A0       A1
  156.  
  157. Having received a command from the rexx server the host has to process
  158. it.   Having  processed  it  the RexxMsg has to be replied so the rexx
  159. server  knows  about the result.  Primary and Secondary are the values
  160. to  be  passed in the result flags of the RexxMsg structure, Result is
  161. optional  and  may  be NULL.  It usually points to a string containing
  162. the result (numeric or string) of the executed command.
  163.  
  164.  
  165. GetRexxCommand() - Get the first argument from a RexxMsg
  166.  
  167. Usage:
  168. String = GetRexxCommand(RexxMessage)
  169.   D0                        D0
  170.  
  171. This  function  is  supported to save the calling program from dealing
  172. with  pointer  offsets  (which  may  be  difficult  with some language
  173. implementations).  It returns a pointer to the first argument entry in
  174. the  supplied  RexxMsg  structure.   This  is  usually a command to be
  175. executed by the host.  If NULL is returned then the RexxMsg is a reply
  176. to a former SendRexxCommand() command.
  177.  
  178.  
  179. GetRexxArg() - Get the first argument from a RexxMsg
  180.  
  181. Usage:
  182. String = GetRexxArg(RexxMessage)
  183.   D0                    D0
  184.  
  185. This  function  is  supported to save the calling program from dealing
  186. with  pointer  offsets  (which  may  be  difficult  with some language
  187. implementations).  It returns a pointer to the first argument entry in
  188. the supplied RexxMsg structure.  This is function does almost the same
  189. as GetRexxCommand(), the string pointer is always returned, no RexxMsg
  190. type consideration is done.
  191.  
  192.  
  193. GetRexxResult1() - Get the first RexxMsg result code
  194.  
  195. Usage:
  196. Result = GetRexxResult1(RexxMessage)
  197.   D0                        D0
  198.  
  199. This  function  is  supported to save the calling program from dealing
  200. with  pointer  offsets  (which  may  be  difficult  with some language
  201. implementations).  It returns the value of the first result code entry
  202. in the supplied RexxMsg structure.
  203.  
  204.  
  205. GetRexxResult2() - Get the second RexxMsg result code
  206.  
  207. Usage:
  208. Result = GetRexxResult2(RexxMessage)
  209.   D0                        D0
  210.  
  211. This  function  is  supported to save the calling program from dealing
  212. with  pointer  offsets  (which  may  be  difficult  with some language
  213. implementations).   It  returns  the  value  of the second result code
  214. entry in the supplied RexxMsg structure.
  215.  
  216.  
  217. GetToken() - Get the next argument from a string
  218.  
  219. Usage:
  220. Argument = GetToken(String,StartChar,AuxBuff,MaxLength)
  221.    D0                 D0      D1       A0       A1
  222.  
  223. GetToken()  implements easy argument parsing.  ARexx posts commands as
  224. null-terminated   strings   with   arguments   separated   by  spaces.
  225. GetToken()  takes a pointer to the command string (String) , a pointer
  226. to  a  counter  variable  (StartChar,  must be a long), a pointer to a
  227. buffer the next argument will be copied to (AuxBuff) and the length of
  228. the  buffer  the  next  argument  will  be copied to (MaxLength).  The
  229. result will a pointer to AuxBuff if an argument was found, NULL if the
  230. end of the command string was reached.
  231.  
  232.  
  233. GetStringValue() - Return the numeric value of a string
  234.  
  235. Usage:
  236. Value = GetStringValue(String)
  237.   D0                     D0
  238.  
  239. Just  like the 'C' language atoi() function GetStringValue() evaluates
  240. the contents of a string.  Its value is returned as a long word.  This
  241. function  helps  to  analyze  the contents of a RexxMsg result code or
  242. command argument.
  243.  
  244.  
  245. BuildValueString() - Turns a number into a string
  246.  
  247. Usage:
  248. String = BuildValueString(Value,String)
  249.   D0                        D0    D1
  250.  
  251. This  function helps to build a string from a numeric value, just like
  252. the  'C'  language  itoa() function.  The supplied string must be long
  253. enough  to  hold  the digits built from Value.  A pointer to the built
  254. string is returned.
  255.  
  256.  
  257.                             -= Credits =-
  258.  
  259. The  rexxhost.library  was  built  from example source code written by
  260. Gary  Samad  &  Bill  Hawes  (fancydemo.c),  extensions  &  additional
  261. functions  were created by Olaf 'Olsen' Barthel.  The library skeleton
  262. code  was  created  using  a  customized  version of Edwin Hoogerbeets
  263. "MkLib"  utility which is based on example source code by Jimm Mackraz
  264. & Neil Katin.
  265.  
  266. The  entire  contents  of  this  library  package  may be used for any
  267. purpose,  no  regard  whether commercial or non-commercial.  No credit
  268. must be given to the creator, nor must a registration fee be paid.
  269.  
  270.                      This IS TRULY PUBLIC DOMAIN!
  271.  
  272.                              -= Author =-
  273.  
  274.                          Olaf 'Olsen' Barthel
  275.                                MXM Gbr
  276.                           Brabeckstrasse 35
  277.                           D-3000 Hannover 71
  278.  
  279.                      Federal Republic of Germany
  280.  
  281.                        Phone: (05 11) 52 23 38
  282.